/*
 * MIT License
 * 
 * Copyright (c) 2017 wen.gu <454727014@qq.com>
 * 
 * Permission is hereby granted, free of charge, to any person obtaining a copy
 * of this software and associated documentation files (the "Software"), to deal
 * in the Software without restriction, including without limitation the rights
 * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
 * copies of the Software, and to permit persons to whom the Software is
 * furnished to do so, subject to the following conditions:
 * 
 * The above copyright notice and this permission notice shall be included in all
 * copies or substantial portions of the Software.
 * 
 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
 * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 * SOFTWARE.
 */

/***************************************************************************
 * Name: tf_thread.h
 *
 * Purpose: thread API implemenation
 *
 * Developer:
 *   wen.gu , 2016-08-08
 *
 * TODO: 
 *
 ***************************************************************************/

#ifndef __tf_THREAD_H__
#define __tf_THREAD_H__

#include "general_type.h"


#ifdef __cplusplus
extern "C" {
#endif

/***************************************************************************
 *
 * macro declaration
 *
 ***************************************************************************/

/** invalid thread id define */
#define TF_INVALID_TID (tf_thread_id)(-1)

/***************************************************************************
 *
 * data structure declaration
 *
 ***************************************************************************/
/** thread id @see also vos_thread_id in vos_thread.h */
typedef void* tf_thread_id;

typedef enum tf_thread_wait_e
{
    TTHD_WaitNothing = 0, /** wait nothing, direct return */
    TTHD_WaitStateChange, /** it doesn't return until change to target state */
}tf_thread_wait_t;

typedef enum tf_thread_priority_e
{
	TTHD_PriorityDefault = 0,
	TTHD_PriorityHigh,
	TTHD_PriorityLow,
}tf_thread_priority_t;


/** tiny thread looper function */
typedef void(*tfThreadFunc_t)(void *);

/***************************************************************************
 *
 * API declaration
 *
 ***************************************************************************/
/**
*@brief  create a thread instance
*
*@param  name   [in] the name of thread.
*@param  timeout_ms  [in] the duration of thread timeout, in milli-second(ms),set 0 to disable this feature
*@param  priority [in] the priority of current thread, @see also tf_thread_priority_t.
*@param  looper   [in] thread looper callback function.
*@param  opaque   [in] the parameter for callback function looper().
*
*@return success: thread instance, fail: NULL .
*@see
*@note   1. thread will not run looper() func until tfThreadResume() be called.
*        2. the default state is paused.
*
*/
G_API GPHD tfThreadCreate(const char* name, GU32 timeout_ms, GU32 priority, tfThreadFunc_t looper, void* opaque);

/**
*@brief  destroy a thread instance
*
*@param  tthd  [in] the handle of thread
*
*@return none.
*@see
*@note  thread must destroy after thread.
*
*/
G_API void  tfThreadDestroy(GPHD tthd);


/**
*@brief  resume current thread
*
*@param  tthd  [in] the handle of thread
*
*@return success: G_OK. fail: error code.
*@see
*@note this operation is async
*
*/
G_API GS32 tfThreadResume(GPHD tthd);


/**
*@brief  pause current thread
*
*@param  tthd   [in] the handle of thread
*@param  wait [in] how wait(see also: tf_thread_wait_t)
*
*@return success: G_OK. fail: error code.
*@see
*
*/
G_API GS32 tfThreadPause(GPHD tthd, tf_thread_wait_t wait);

/**
*@brief  stop current thread
*
*@param  tthd [in] the handle of thread
*
*@return success: G_OK. fail: error code.
*@see
*@note 1. this operation is sync mode
*      2. must call this API ,before destroy thread.
*      3. atfer this operation, the tfThreadCheckTerminated() will return GTRUE.
*
*/
G_API GS32 tfThreadStop(GPHD tthd);

/**
*@brief  check is need terminate current thread
*
*@param  tthd [in] the handle of thread
*
*@return need: GTRUE. needn't: GFALSE.
*@see
*@note void thread_looper(* opaque)
*      {
*		  GPHD thd = ((xxx)(opaque))->thd;
*
*		  while(tfThreadCheckTerminated(thd) != GTRUE)
*		  {
*		    ....
*		  }
*	   }
*
*/
G_API GBOL tfThreadCheckTerminated(GPHD tthd);


/**
*@brief  check current thread is timeout
*
*@param  tthd [in] the handle of thread
*
*@return timeout: GTRUE. doesn't: GFALSE.
*@see
*
*/
G_API GBOL tfThreadIsTimeout(GPHD tthd);


/**
*@brief  get thread id by thread handle
*
*@param  tthd [in] the handle of thread
*
*@return success: thread id, fail: TF_INVALID_TID 
*@see
*
*/
G_API tf_thread_id tfThreadGetTid(GPHD tthd);


#ifdef __cplusplus
}
#endif

#endif //end of __tf_THREAD_H__
